Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / bbskit.zip / BBSKIT.DOC < prev next >

Wrap

Text File | 1991-04-12 | 118KB | 5,404 lines

BBSkit A Turbo Pascal unit for the BBS author Written by Steve Madsen This manual and the BBSkit units are copyright (c) 1991 by Steven Madsen. All rights reserved. Throughout this manual, references are made to other products: IBM is a registered trademark, and PC-DOS is a trademark of, International Business Machines Corporation. MS-DOS is a trademark of Microsoft Corporation. Macintosh is a trademark of Apple Computer, Inc. Borland and Turbo Pascal are registered trademarks of Borland International, Inc. Touch-Tone is a registered trademark of American Telephone & Telegraph. This program is being provided to you on a trial basis. It is being marketed under the ShareWare idea. If you find this product useful, you are expected to register it with the author for $40 in United States funds. This registration fee includes a registered version of the software, a printed user's manual, free support from the author, and update notices. Send registration fees to: Steven Madsen 1888 Edith Marie Drive Beavercreek, OH 45431 Please specify 5.25" or 3.5" disk sizes. All registrations must be in the form of a check or money order, made out to Steven Madsen. Please allow 4 to 6 weeks for delivery of your order. Registered versions of BBSkit include Xmodem/CRC, Xmodem/1K and Zmodem batch protocol support for send/receive, lots of sample code for things such as chat mode, time limits, and color, and a utility to create your own terminal emulation templates. The registered version will also clear the two second product plug at the beginning of all products written with BBSkit. BBSkit Manual Page 2 Table of Contents Chapter 1: Getting Started Chapter 1: Getting Started Chapter 1: Getting Started.............................4 BBSkit Overview........................................4 The Modem..............................................4 The Serial Connection..................................5 The Computer (and Software)............................5 Chapter 2: Programming with BBSkit Chapter 2: Programming with BBSkit Chapter 2: Programming with BBSkit....................7 Inheriting TBBS........................................7 Expanding TBBS.........................................7 Overriding Critical Methods............................7 Chapter 3: BBSkit Methods & Types Chapter 3: BBSkit Methods & Types Chapter 3: BBSkit Methods & Types.....................11 BBSkit Manual Page 3 Getting Started Chapter 1 BBSkit Overview BBSkit was developed because there was a lack of software packages available for the sysop who didn't want to run someone else's software. It was created with the idea that writing a BBS shouldn't be mostly low-level work with the modem and serial port, that it should be honing your user interface to perfection. BBSkit does its best to take out all the hard work, and leave the path open for your ideas to take form. BBSkit is more than a BBS toolkit. It has the capability of writing complete door programs, accessible to other, pre-written software. The only requirement is that your host BBS software also uses a FOSSIL driver. BBSkit can still take care of all the low-level work. The program was created with Turbo Pascal 6.0, and will run on any version from 5.5 or later. The reason? BBSkit makes use of the later version's implementation of objects. An object is like a Pascal record record record, but it also includes the code that makes use of the data, binding both code and data into one variable type. By making use of objects, BBSkit can be provided as a unit, yet it is still completely expandable because the whole program is one giant object: TBBS TBBS TBBS. (At this point, if you are unsure what an object is, you should consult your manuals. Pascal 5.5 came with an "OOP Guide," which is exactly what you want to read to learn all about objects. Pascal 6.0 has included the "OOP Guide" in the "User's Guide," chapter four.) BBSkit provides a host of features: * Redirection of I/O in any of up to 16 combinations. * Complete support for FOSSIL driven serial I/O. * Optional inactivity timeout from keyboard or serial port. * Optional automatic carrier checking. * Control of line feeds after carriage return for remote users. * Optional pause after each screen of text. * Built-in Xmodem for file send & receive. * Completely expandable TBBS object. * User overrideable methods during a ComReadKey or ComReadKeyE. * ANSI and non-ANSI terminal emulation, with 14 templates provided. * and more! The Modem Required equipment for any computer bulletin board system is a modem connected to your computer. BBSkit is no different. Modems are either internal or external. An BBSkit Manual Page 4 internal modem is one that is plugged directly into the computer through one of your computer's slots; it is completely hidden from view and takes up no desk space. An external modem is one that sits on your desk. It usually has lights that let you know what the modem is doing at any given time. One type of modem is not superior in any way to another. Both get the job done. Refer to your modem's manual for instructions on how to connect it to your computer if it has not been done already. Unfortunately, there was a time when modems were not standardized. BBSkit requires the use of a Hayes-compatible modem for dialing, answering the phone, or any other activity that is modem related and directly supported by BBSkit. The modem must be capable of reporting the actual carrier signal to the computer through the DCD (data carrier detect) line. Some modems have DIP switches that tell the modem to report DCD as high all the time. If this is the case, the modem must be configured to report DCD as high only when the modem is actually connected to another computer. Refer to your manual for properly configuring your modem. The Serial Connection BBSkit also requires that your modem be connected to your computer through a RS-232C serial port connected to any communications port from COM1: through COM4:. (If you have an internal modem, refer to your manuals for installation. Internal modems also have the side benefit of providing a serial port for you, so you may skip this section.) An RS232C is what your computer uses to communicate with serial devices, such as your modem and sometimes a mouse. Connecting the modem through a cable to your serial port allows BBSkit to drive the modem. Generally, any serial port driver by an 8250 chip or a 16550 chip will be compatible with BBSkit. (BBSkit does not support the extended features of a 16550.) As a rule, if your modem works with your computer, then BBSkit will work with your modem. External modems must use serial cables which are capable of detecting signals that the modem can report, such as the carrier detect line. Most serial cables are capable of reporting the correct signal, so this should not prove to be a problem. The Computer (and Software) Any IBM-compatible computer running an 80x86 microprocessor will support BBSkit. You also must be running either PC-DOS or MS-DOS version 2.10 or higher, and have Turbo Pascal version 5.5 or higher. BBSkit is provided as a unit for both versions 5.5 and 6.0 of Turbo Pascal. Version 5.5 units are not compatible with version 6.0 of BBSkit Manual Page 5 Pascal, and vice versa, so be sure you use the correct unit or Pascal will give you an error when you attempt to compile a program. Memory requirements vary from version to version of Pascal, and depend on the environment you choose to work in (integrated or command-line). BBSkit does not make use of any expanded or extended memory, and will not interfere with any RAM disks or disk caches installed. Overlays are supported by Pascal while BBSkit is in use. In addition to that, you will need a copy of a FOSSIL driver, such as Ray Gwinn's X00 or David Nugent's BNU. A FOSSIL driver is what BBSkit uses to interface to your modem. The FOSSIL driver takes care of low-level serial I/O, and provides features that a built-in interface would have difficulty handling. BBSkit is compatible with any type of DOS disk device, such as hard drives, 5.25" and 3.5" drives (normal and high density). BBSkit also supports the use of a printer, connected to any port recognizable by Pascal and the Write(Lst, ...) command (usually LPT1:). BBSkit also supports the extended text displays of the EGA (80x43) and the VGA (80x50), but it does not support graphics mode directly. (But what's to stop you from expanding TBBS if you really want to write a BBS in graphics mode?) BBSkit Manual Page 6 Programming with BBSkit Chapter 2 Inheriting TBBS The very first thing you will want to do before anything else in your BBSkit enhanced programs is inherit the TBBS object, which is the platform for the entire BBSkit unit. Inheriting is simply the process of defining a new type type type, which will have all the properties of the parent type, as well as any new qualities you may want to add. Inheritance is unique to objects and object oriented programming. Inheriting TBBS is simple: TMyBBS = object(TBBS) end; These two lines would go under your Type Type Type declarations at the top of your program. Essentially, all you have done here is created a new object called TMyBBS that is identical with the TBBS object that is provided. Still, to expand TBBS and write a BBS or anything else using the BBSkit enhancements, it is a requirement. Expanding TBBS Left alone, TBBS can't run a BBS for you, or become a full featured terminal program. TBBS simply provides the tools to create such programs. To make use of BBSkit's abilities, you have to write some code to drive them. The only way to do that is to add your procedures and functions to the original TBBS definition by expanding the inherited object. Let's say you wanted to jump right in and start adding to the object: TMyBBS = object(TBBS) PROCEDURE MyProcedure; end; This would tell Pascal that you want to add a procedure definition (called a method) to your object definition. To complete the process, you would then write a procedure somewhere in your code called TMyBBS.MyProcedure TMyBBS.MyProcedure TMyBBS.MyProcedure. It is very important that the TMyBBS header is in front of each of your procedures or functions so that Pascal knows where to find the code at compile time. This is the point where you really need to know the basics of objects if you don't already. Overriding Critical Methods TBBS alone provides three methods that are designed to provide a base from which to drive BBSkit programs. They are: BBSkit Manual Page 7 CONSTRUCTOR Init; PROCEDURE Run; VIRTUAL; DESTRUCTOR Done; VIRTUAL; These three methods are described in more detail here. Run Run Run is empty as provided, so it does absolutely nothing when called directly without modification. Init Init Init initializes the internal emulation table for TTY emulation and opens a "file" to send text through DOS instead of directly to the screen. It is important that you call TBBS.Init TBBS.Init TBBS.Init within your Init Init Init code. The keyword virtual is important, however. A virtual method is one that is overrideable by the programmer. Overrideable means that the programmer can actually rewrite the method without destroying the old version. Instead, the new version replaces the old one in your newly created object. In essence, it means that you can call both versions, and they can do completely different actions, but they can have the same method name. The only difference would be the object they reside in. Remember, though, that virtual methods that have been overridden by the programmer also must have the virtual keyword following the method definition, but not where the method is defined in the code. Init Init Init is a method provided for initializing your system's variables and serial port. Code in Init should only be run once, and then when the program is first executed. Though this method does not have a virtual keyword, it is overrideable by the programmer. (It does not need the virtual keyword because it is a constructor constructor constructor. Constructors are usually used for dynamically allocated objects, but it is used here for simplicity's sake and to keep things consistent.) A runtime error will be generated if you do not call TBBS.Init before making an call to an output routine that is part of BBSkit. Run Run Run is a method that does all the work for your program. Here is where your BBS would wait for calls, accept a user login, let the user roam your system, and finally disconnect and recycle for another called. Never should a user still be online when this method returns control back to the main block, unless you really know what you are doing. Done Done Done is the method that cleans up after the BBS. It should close any files that were opened along the way, shut down the serial port, make sure there is no called online to access DOS when the program quits, and any other housecleaning tasks you set down for it. TBBS.Done should be the last line in your own Done method, as this will close the "file" set up by TBBS.Init. Programmed like this, BBSkit is set up to have most main blocks of any program look something like this: Var BBS : TMyBBS; { create an instance of your object } BBSkit Manual Page 8 BEGIN BBS.Init; BBS.Run; BBS.Done; END. Remember that the whole idea behind objects is to encapsulate your code and data into one data type. Any variables you use also should be declared as part of your object, and most of your BBS should be included inside your object, except some minor routines that might be used from other units you may have. However, also keep in mind that BBSkit is designed as a programmer's toolkit, not as a framework for an already existing BBS. You are free to design your interface to something that you you you like. Feel free to experiment! The possibilities are endless! BBSkit Manual Page 9 BBSkit Methods & Types Chapter 3 What follows is a complete, alphabetical listing of the methods, types, procedures, and functions provided in the untouched TBBS object and in the BBSkit unit. Each will follow a general pattern: FUNCTION ChWaiting : Boolean; FUNCTION ChWaiting : Boolean; FUNCTION ChWaiting : Boolean;1 1 1 ChWaiting returns a boolean value reflecting the state of the input buffer of the current COM port. It returns true if at least one character is waiting to be processed, 2 2 2 and False if no characters are waiting. Sample Program Sample Program Sample Program3 3 3 if (ChWaiting) then WriteLn('Character(s) waiting to process.') else WriteLn('No characters waiting.'); See Also: See Also: See Also: Incoming.4 4 4 1: 1: 1: An example of the method header, what variables are passed to it, and the type of the return value (if any). 2: 2: 2: A short description of the method. 3: 3: 3: A short example block of code showing how the method might be used in a real situation. 4: 4: 4: A reference to other methods that have a relation to the current method. Please note that procedures and functions that do not include the "TBBS." header before their name are not not not TBBS methods. Rather, they are simply procedures and functions that were needed while developing BBSkit, but didn't really belong inside the TBBS object. They are still freely usable throughout the TBBS object and any of its descendents. BBSkit Manual Page 10 Backspace FUNCTION Backspace(Num : Byte) : String; FUNCTION Backspace(Num : Byte) : String; FUNCTION Backspace(Num : Byte) : String; Backspace is useful for erasing text immediately preceeding the cursor in a BBS-style setting, where it sometimes isn't possible to easily erase text with quick commands. It will return a string containing Num combinations of #8#32#8 (backspace, space, backspace), which is capable of erasing Num characters before the cursor. The cursor will also be moved back Num characters on-screen. Some terminals, such as IBM and compatibles, generally allow the cursor to act non-destructively, which means the cursor can backspace onto existing characters without overwriting them. Other terminals, such as the Macintosh, make the cursor act destructively, erasing each character they backspace over. Using the backspace function ensures that all terminals show the same thing, regardless of how their system treats a backspace character. BBSkit Manual Page 11 CarrierLost FUNCTION TBBS.CarrierLost : Boolean; FUNCTION TBBS.CarrierLost : Boolean; FUNCTION TBBS.CarrierLost : Boolean; CarrierLost keeps track of the remote carrier status during any wait-for-key loops. It returns a value reporting whether carrier was lost while your code was waiting for a keypress. After returning a TRUE value, your code should handle the situation accordingly. Note that CarrierLost only returns TRUE if there was a remote carrier to begin with. CarrierLost can also be called in your code to find out if the remote carrier was dropped since the last check was made. CarrierLost does not reset its internal flag until after a Hangup call is issued. Therefore, you are safe to make multiple calls to CarrierLost after carrier was dropped, and still get the same result. Sample Program Sample Program Sample Program if (CarrierLost) then LogoutUser else DisplayMainMenu; See Also: See Also: See Also: SetCarrierChk, Hangup. BBSkit Manual Page 12 Center FUNCTION Center(Strn : String) : String; FUNCTION Center(Strn : String) : String; FUNCTION Center(Strn : String) : String; Center formats Strn to be center justified on a normal 80 column screen, and returns the new string as the function result. Spaces are padded at the beginning of the string to center it out. See Also: See Also: See Also: Left, Right, Space. BBSkit Manual Page 13 ChWaiting FUNCTION TBBS.ChWaiting : Boolean; FUNCTION TBBS.ChWaiting : Boolean; FUNCTION TBBS.ChWaiting : Boolean; ChWaiting returns a boolean value reflecting the state of the input buffer of the current COM port. It returns true if at least one character is waiting to be processed, and False if no characters are waiting. Sample Program Sample Program Sample Program if (ChWaiting) then WriteLn('Character(s) waiting to process.') else WriteLn('No characters waiting.'); See Also: See Also: See Also: Incoming. BBSkit Manual Page 14 ClearReceive PROCEDURE TBBS.ClearReceive; PROCEDURE TBBS.ClearReceive; PROCEDURE TBBS.ClearReceive; ClearReceive removes any waiting characters from the current COM port immediately, without processing them. Sample Program Sample Program Sample Program if (CarrierLost) then begin ClearTransmit; ClearReceive; LogoutUser; end else DisplayMainMenu; See Also: See Also: See Also: ClearTransmit. BBSkit Manual Page 15 ClearTransmit PROCEDURE TBBS.ClearTransmit; PROCEDURE TBBS.ClearTransmit; PROCEDURE TBBS.ClearTransmit; ClearTransmit removes any characters waiting to be transmitted out the COM port immediately, without waiting to send them. Sample Program Sample Program Sample Program if (CarrierLost) then begin ClearTransmit; ClearReceive; LogoutUser; end else DisplayMainMenu; See Also: See Also: See Also: ClearReceive. BBSkit Manual Page 16 ClosePort PROCEDURE TBBS.ClosePort(LowerDTR : Boolean); PROCEDURE TBBS.ClosePort(LowerDTR : Boolean); PROCEDURE TBBS.ClosePort(LowerDTR : Boolean); Closes the current COM port down. If LowerDTR is TRUE, then the DTR line to the modem will also be lowered before the port is closed. On program exit, DTR should be lowered. For any shells to external programs that need to send and receive data from the user, LowerDTR should be FALSE. (Some modems place the phone on-hook when DTR is lowered.) Generally called from TBBS.Done before quitting the program. Note: no data can be sent out the port once it has been closed. It must first be re-opened. Sample Program Sample Program Sample Program if (Quit = True) then ClosePort else WaitForNextCall; See Also: See Also: See Also: OpenPort. BBSkit Manual Page 17 Cls PROCEDURE TBBS.Cls; PROCEDURE TBBS.Cls; PROCEDURE TBBS.Cls; Clears the screen at the local and/or remote terminals, depending on the settings of SetOutput. Screen clears on the remote terminal are always accomplished with terminal emulation. If no terminal emulation is specified, TTY is used as default and a character code of 12 (^L) is sent. Most terminals interpret this as a screen clear code. See Also: See Also: See Also: Emu_ClearScreen, SetOutput. BBSkit Manual Page 18 ComReadKey FUNCTION TBBS.ComReadKey : Char; FUNCTION TBBS.ComReadKey : Char; FUNCTION TBBS.ComReadKey : Char; This is the basic function used when waiting for a key from the remote user or local keyboard. Optionally, the carrier is watched, timeouts are observed, and local function keypresses are handled. If no key is waiting at either the modem or keyboard, ComReadKey will wait for one. Where the key comes from depends on settings made with the SetInput procedure. Sample Program Sample Program Sample Program Ch := UpCase(ComReadKey); case Ch of 'M' : MessageSection; 'F' : FilesSection; 'G' : Goodbye; else ComWriteLn('Illegal command.'); end; See Also: See Also: See Also: ComReadKeyE, ComReadLn, ComReadLnWrap, SetCarrierChk, SetInput, SetTimer, SetTimerDelay. BBSkit Manual Page 19 ComReadKeyE FUNCTION TBBS.ComReadKeyE; FUNCTION TBBS.ComReadKeyE; FUNCTION TBBS.ComReadKeyE; ComReadKeyE functions exactly like its counterpart ComReadKey, except ComReadKeyE will also echo the pressed key to either the screen, the modem, or both, depending on the settings from SetOutput. If SetEcho has been used to set the echo to anything except #0 (null), then that character will be echoed back to the user instead of the character typed. See Also: See Also: See Also: ComReadKey, SetEcho, SetOutput. BBSkit Manual Page 20 ComReadLn PROCEDURE TBBS.ComReadLn(var Inp : String; Max : Byte); PROCEDURE TBBS.ComReadLn(var Inp : String; Max : Byte); PROCEDURE TBBS.ComReadLn(var Inp : String; Max : Byte); ComReadLn is the main procedure for accepting a line of input from the user. It rejects all controls codes except the following: ^H (#8) Backspace with rubout ^I (#9) Tab to next tabstop ^M (#13) Enter ^X (#24) Line erase, start at beginning Max is the maximum number of characters it will accept on one line. If Max is reached, no other non-editing characters (those above) will be accepted. The line as entered by the user or local terminal will be returned in Inp. ComReadLn is affected by all standard BBSkit watches, such as carrier checking and timeout, as well as accepting input based on the SetInput procedure. If Max is equal to zero, then no characters except a carriage return (enter) will be accepted. This may be useful for any "Press enter to continue..." prompts you may have. Sample Program Sample Program Sample Program ComWrite('Enter your first name: '); ComReadLn(Username, 30); See Also: See Also: See Also: ComReadLnWrap, SetEcho. BBSkit Manual Page 21 ComReadLnWrap PROCEDURE TBBS.ComReadLnWrap(var Inp : String; Max : Byte; PROCEDURE TBBS.ComReadLnWrap(var Inp : String; Max : Byte; PROCEDURE TBBS.ComReadLnWrap(var Inp : String; Max : Byte; var Wrap : String); var Wrap : String); var Wrap : String); This procedure is identical to ComReadLn, except it adds the Wrap parameter. It is primarily intended for the creation of line editors. When the user attempts to type past the end of the line (as defined by Max), the partial word being entered is stripped from the end of Inp and stuffed into Wrap. This also applies to data already in Wrap before calling ComReadLnWrap. Any data in Wrap at the start of the procedure is stuffed into the first part of Inp. Thus, multiple calls to ComReadLnWrap will allow the user to enter everything he wants to, without having to hit return at the end of a line. Sample Program Sample Program Sample Program Wrap := ''; { empty it before calling ComReadLnWrap } CurLine := 0; Repeat Inc(CurLine); { increment CurLine by 1 } ComReadLn(Buffer[CurLine], 78, Wrap); { read line } Until (Buffer[CurLine] = '/s'); { until /s is typed } See Also: See Also: See Also: ComReadLn. BBSkit Manual Page 22 ComWrite PROCEDURE TBBS.ComWrite(Strn : String); PROCEDURE TBBS.ComWrite(Strn : String); PROCEDURE TBBS.ComWrite(Strn : String); ComWrite sends Strn out the modem and/or to the local screen without issuing a newline at the end of Strn. In other words, the cursor is left "dangling." If page pausing is active, you should not imbed carriage returns (#13) within Strn, or page pausing will not be able to keep track of the lines that have been sent out. See Also: See Also: See Also: ComWriteLn, SetOutput, SetPaging, SetPagingLines, SetPagingMsg. BBSkit Manual Page 23 ComWriteLn PROCEDURE TBBS.ComWriteLn(Strn : String); PROCEDURE TBBS.ComWriteLn(Strn : String); PROCEDURE TBBS.ComWriteLn(Strn : String); ComWriteLn sends Strn out the modem and/or to the local screen, depending on the settings of SetOutput. If page pausing is set with the SetPaging and SetPagingLines procedures, this function will keep track of the number of carriage returns sent out the modem and pause when a full screen has been reached. However, you should not not not send imbedded carriage returns in your strings, as ComWriteLn does not currently check for those characters. For example, don't do this: ComWriteLn(#13#13); if you wanted to skip three lines. Instead, just call ComWriteLn('') three times and keep the line counter in sync with the actual number of lines sent out. See Also: See Also: See Also: ComWrite, SetOutput, SetPaging, SetPagingLines, SetPagingMsg. BBSkit Manual Page 24 CopyFile FUNCTION CopyFile(Source, Dest : String) : Boolean; FUNCTION CopyFile(Source, Dest : String) : Boolean; FUNCTION CopyFile(Source, Dest : String) : Boolean; CopyFile copies the source file contained in Source to the destination path or file contained in Dest. CopyFile can intelligently determine whether Dest is a path to a directory, or a path to a file, and act accordingly. If Dest is a path to a directory, CopyFile simply copies the file Source to the destination directory Dest. If Source is invalid, or if CopyFile encounters an error (such as a disk full, or a problem inside the file such as a bad sector), the function will return FALSE. If no errors are encountered, TRUE is returned. If Dest is a path to a file, CopyFile will copy the file Source over the file Dest. Any data contained by Dest is forever lost, because CopyFile will also overwrite the directory entry (which what a file undeleter uses). The return value is FALSE if any errors are encountered, and TRUE if no errors were encountered. In either case, if Source is invalid, or if Dest is a path to directory which does not exist (example: C:\TEMP\ if TEMP does not exist off of C:'s root directory), then CopyFile will return FALSE. BBSkit Manual Page 25 Date FUNCTION Date : String; FUNCTION Date : String; FUNCTION Date : String; Date returns the current date from the internal clock (if any) or from DOS (if there is no clock) in the form MM/DD/YY. For months, days, and years that have no tens digit (such as January 1, 2001), the empty space will be filled with a zero. Therefore, January 1, 2001 would format to 01/01/01. The string returned by Date will always always always be 8 characters in length. See Also: See Also: See Also: Time. BBSkit Manual Page 26 Dial PROCEDURE TBBS.Dial(Number : String); PROCEDURE TBBS.Dial(Number : String); PROCEDURE TBBS.Dial(Number : String); Dial attempts to send an "ATD..." command out to your Hayes-compatible modem to dial a number. If your phone lines do not support Touch-Tone dialing, make sure Number has a P as its first character, which will force pulse dialing. The programmer is expected to check for success or failure of the call, and whether or not a carrier was detected. Sample Program Sample Program Sample Program Dial('555-1234'); WaitFor('C', 30); {wait 30 seconds for a 'C'. A 'NO} {CARRIER' will return success, as } {will a 'CONNECT' } if (Online) then begin ComReadLn(Result, 40); Bps := StrToInt(Copy(Result, 8, 5)); if (Bps = 0) then Bps := 300; SetBps(Bps); TerminalMode(Full); end; See Also: See Also: See Also: TerminalMode. BBSkit Manual Page 27 Emu_... PROCEDURE TBBS.Emu_...(...); PROCEDURE TBBS.Emu_...(...); PROCEDURE TBBS.Emu_...(...); These methods are provided for BBSkit to interface with a number of ANSI and non-ANSI terminals with as little trouble as possible. Templates are loaded in with the LoadEmulation method, and the codes are accessed with these calls. Additional templates must be created with the EmuMaker program, provided on the distribution disk. The methods currently available are: GotoXY(X, Y : Byte) Goes to the screen location at X, Y. CursorUp Moves the cursor up one line. CursorDown Moves the cursor down one line. CursorLeft Moves the cursor left one column. CursorRight Moves the cursor right one column. ClearScreen Clears the screen, places cursor at 1,1. ClearToTop Clears from cursor line to top of screen, cursor position is unchanged. ClearToEndOfScreen Clears from cursor line to bottom of screen, cursor position is unchanged. ClearToEndOfLine Clears from cursor column to the end of the line the cursor is on. Cursor position is unchanged. ReverseVideo Swaps the foreground and background color attributes. Sometimes called "inverse video." NormalVideo Swaps the foreground and background color attributes. Cancels the effects of ReverseVideo. ScrollUp Moves the entire screen up one line. Top line is lost. ScrollDown Moves the entire screen down one line. Bottom line is lost. InsertLine Inserts a blank line before the line the cursor is on. All other lines below the cursor line are moved down one line, and the bottom line is lost. DeleteLine Deletes the cursor line, and moves all lines below it up one line. A blank line is inserted at the bottom of the screen. InsertChar Inserts a space at the cursor position. All other characters following the cursor on the current line are moved to the left one character. Any character in the BBSkit Manual Page 28 Emu_... 80th column is lost. DeleteChar Deletes the character under the cursor. All other characters following the cursor on the current line are moved to the left one character. A space is inserted at column 80. Color(Fore, Back:Byte) Changes the foreground color to Fore, and the background color to Back. For ANSI.EMU, ReverseVideo ReverseVideo ReverseVideo and NormalVideo NormalVideo NormalVideo have some special properties. ReverseVideo and NormalVideo simply swap the foreground and background colors; there is no real inverse video or normal video in ANSI.EMU. So, two calls to ReverseVideo would be the same as one to ReverseVideo and one to NormalVideo. These methods must be handled with care, or the other emulations will get funny results from your code. For blinking colors, Color Color Color must be passed a background color of greater than 7. This will result in the background color being (Back - 7) and the foreground color will blink. Remember that all calls must be prefixed with Emu_, so a call to CursorUp, for example, would look like this: Emu_CursorUp; See Also: See Also: See Also: LoadEmulation. BBSkit Manual Page 29 Exist FUNCTION Exist(Filename : String) : Boolean; FUNCTION Exist(Filename : String) : Boolean; FUNCTION Exist(Filename : String) : Boolean; Exist returns TRUE if Filename exists. Wildcards can be passed as a filename, and if any files are found in the path specified by the beginning of Filename, Exist will still return TRUE. Exist cannot find files which are hidden from a normal DIR command from DOS. For example, to find out if there are any files matching the mask *.COM in the C:\DOS\ directory, execute Exist like this: if (Exist('C:\DOS\*.COM')) then WriteLn('Found!'); BBSkit Manual Page 30 F... & ...Arrow FUNCTION TBBS.F... : Boolean; VIRTUAL; FUNCTION TBBS.F... : Boolean; VIRTUAL; FUNCTION TBBS.F... : Boolean; VIRTUAL; FUNCTION TBBS....Arrow : Boolean; VIRTUAL; FUNCTION TBBS....Arrow : Boolean; VIRTUAL; FUNCTION TBBS....Arrow : Boolean; VIRTUAL; These methods are those called by ComReadKey, ComReadKeyE, ComReadLn, and ComReadLnWrap whenever a function key or arrow key is pressed on the local keyboard. When such an event occurs, control is briefly passed to the appropriate routine, and a user-defined action can then take place. For example, if F1 were pressed, TBBS.F1 TBBS.F1 TBBS.F1 would be called. These methods are provided empty. It is their purpose to provide the programmer with several empty methods that can be filled with local mode actions. A BBS might use the function keys for various sysop actions, such as initiating a chat session with ther user, editing his security, toggling the printer, toggling the "sysop is available" flag, and virtually anything else the programmer wants. Keep in mind, though, that the purpose of the methods is to allow the sysop to do things while a user is online without that user being able to notice any time lagging. Therefore, the routines should be kept simple, except in cases where you want want want the user to know something is happened, such as a chat session. Function keys F1 throught F12 are provided. (F11 and F12 are only available on AT-style machines, however.) All four arrow keys are provided as well, and all of the routines are virtual virtual virtual. The return values for these routines are all of the Boolean type. In almost all circumstances, the value returned should be FALSE. However, there are times when the key pressed could eject the user from a BBS. In these circumstances, when you do not not not want the user to finish the input that was interrupted, the return value should be TRUE. BBSkit Manual Page 31 GetAnswerMode FUNCTION TBBS.GetAnswerMode : Byte; FUNCTION TBBS.GetAnswerMode : Byte; FUNCTION TBBS.GetAnswerMode : Byte; GetAnswerMode returns a byte value corresponding to one of two constants defined for the way your modem will answer the phone. In Originate Originate Originate mode, BBSkit will send the ATD string, which simulates originating a call, and proceed to wait for a carrier. In Answer Answer Answer mode, BBSkit will send ATA and wait for the remote modem to connect to the carrier being sent. This method does not do anything for your program. Rather, it is provided for your program to keep track of what mode it might be in at any given time. There are other methods which do the "work" of picking up the phone and connecting. Sample Program Sample Program Sample Program A := GetAnswerMode; case A of Originate : WriteLn('In originate mode.'); Answer : WriteLn('In answer mode.'); end; See Also: See Also: See Also: PickupPhone, SetAnswerMode. . . BBSkit Manual Page 32 GetBps FUNCTION TBBS.GetBps : LongInt; FUNCTION TBBS.GetBps : LongInt; FUNCTION TBBS.GetBps : LongInt; GetBps returns the current operating speed in bits per second on the current COM port. If you have not set the bit rate previously, GetBps will return a -1. Sample Program Sample Program Sample Program WriteLn('Operating at ', GetBps, 'bps.'); See Also: See Also: See Also: SetBps. BBSkit Manual Page 33 GetInput PROCEDURE TBBS.GetInput(var Con, Rem : Boolean); PROCEDURE TBBS.GetInput(var Con, Rem : Boolean); PROCEDURE TBBS.GetInput(var Con, Rem : Boolean); GetInput returns the conditions of input redirection in Con and Rem which were previously set by a call to SetInput. If input is being accepted from the local keyboard, Con will return TRUE. If input is being accepted from the modem, Rem will return TRUE. In either case, if input is not being accepted, a FALSE value will be returned. This method is mainly used for "remembering" the old settings of input redirection when your program goes off to do something that only the local operator is supposed to know about (such as verifying a new user on a BBS). See Also: See Also: See Also: GetOutput, SetInput, SetOutput. BBSkit Manual Page 34 GetOutput PROCEDURE TBBS.GetOutput(var Con, Rem : Boolean); PROCEDURE TBBS.GetOutput(var Con, Rem : Boolean); PROCEDURE TBBS.GetOutput(var Con, Rem : Boolean); GetOutput returns the conditions of output redirection in Con and Rem which were previously set by a call to SetOutput. If output is being sent to the local screen, Con will return TRUE. If output is being sent out the serial port to the modem, Rem will return TRUE. In either case, if output is not being sent, a FALSE value will be returned. This method, like GetInput, is mainly used for "remembering" the old values of output redirection, and is usually used in conjunction with GetInput. See Also: See Also: See Also: GetInput, SetInput, SetOutput. BBSkit Manual Page 35 GetScreenStr PROCEDURE GetScreenStr(X1, X2, Y : Byte; var St : String); PROCEDURE GetScreenStr(X1, X2, Y : Byte; var St : String); PROCEDURE GetScreenStr(X1, X2, Y : Byte; var St : String); GetScreenStr copies characters from the local screen into the string St. All characters on line Y, from X1 to X2, inclusive, are copied into the string. The resulting string is then of exact length of the characters you wanted to copy. Note that this procedure acts completely independent of any Window(...) calls that have been made, so you may need to use the WindMin CRT variable to obtain the desired text. Applications for this procedure are saving the local screen for a DOS shell, so that the entire screen is restored when the DOS shell is exited from, and reminding the user of where he was before a chat session was initiated. (You can copy the entire line that the cursor is on when chat is entered, and when it is exited, rewrite it back to the screen. Usually, that line you copied was a prompt of some sort.) BBSkit Manual Page 36 GetScreenWord PROCEDURE GetScreenWord(X, Y : Byte; var Attr : Byte; var Ch PROCEDURE GetScreenWord(X, Y : Byte; var Attr : Byte; var Ch PROCEDURE GetScreenWord(X, Y : Byte; var Attr : Byte; var Ch : Char); : Char); : Char); GetScreenWord finds the character and attribute values for the screen location X,Y and returns them in Attr and Ch. X,Y are absolute screen coordinates, not relative to the current window. GetScreenWord goes directly to video memory. See Also: See Also: See Also: PutScreenWord. BBSkit Manual Page 37 GetText PROCEDURE GetText(X1, Y1, X2, Y2 : Byte; var Dest); PROCEDURE GetText(X1, Y1, X2, Y2 : Byte; var Dest); PROCEDURE GetText(X1, Y1, X2, Y2 : Byte; var Dest); GetText is the text-mode equivalent of GetImage. X1, Y1 are the coordinates of the upper left corner of the block of text you wish to copy. X2, Y2 are the coordinates of teh lower right corner. All coordinates are absolute, not relative to the current window. Dest is an untyped variable parameter. It should be passed the pointer to a location in memory that you wish to place the text captured. Text captured will retain its attribute byte as well as the character seen. The memory required for a GetText image is calculated through the TextMemSize function. Sample Program Sample Program Sample Program Var Dest : Pointer; BEGIN GetMem(Dest, TextMemSize(1, 1, 10, 10)); {get memory} GetText(1, 1, 10, 10, Dest^); {get the text} ClrScr; {clear the screen} ReadLn; {wait for user} PutText(1, 1, Dest^); {put text back} END. See Also: See Also: See Also: PutText, TextMemSize. BBSkit Manual Page 38 Hangup FUNCTION TBBS.Hangup : Boolean; FUNCTION TBBS.Hangup : Boolean; FUNCTION TBBS.Hangup : Boolean; Hangup will attempt to hang up the modem if it is currently off-hook. BBSkit will first try to lower the Data Terminal Ready (DTR) line for two seconds. This makes most modems drop carrier if they are online. If this fails, Hangup will then try to send the attention string (default is +++, but can be changed by AT commands), followed by ATH0. If this also fails, a FALSE value will be returned to the calling routine. If the DTR drop succeeds, BBSkit will not attempt to send the hangup string to the modem. If Hangup is successful in dropping carrier, a TRUE value will be returned. Sample Program Sample Program Sample Program if (not Hangup) then WriteLn('Unable to hangup!') else WriteLn('Disconnected with remote modem.'); See Also: See Also: See Also: Online. BBSkit Manual Page 39 HideCursor PROCEDURE HideCursor; PROCEDURE HideCursor; PROCEDURE HideCursor; HideCursor turns the cursor off on the local screen. It is intended for turning off the cursor when text is being continuously shown in the same area, without a flickering cursor creating a static effect on screen. Most of the time, the cursor should be on. The cursor can be turned back on with the ShowCursor procedure. See Also: See Also: See Also: ShowCursor. BBSkit Manual Page 40 Incoming FUNCTION TBBS.Incoming : Boolean; FUNCTION TBBS.Incoming : Boolean; FUNCTION TBBS.Incoming : Boolean; Incoming reports a boolean value depending on the status of the input buffer of the serial port, and the keyboard buffer of the local terminal. If either the FOSSIL driver or the keyboard reports a key waiting, Incoming returns a TRUE value. Otherwise, Incoming returns a FALSE. Incoming does does does check the status of input redirection, and will not consider a device if BBSkit is not currently accepting input from it. Note that this method does not distinguish between the keyboard or the modem. It simply returns a value reporting whether or not a key is waiting at either device. Sample Program Sample Program Sample Program if (Incoming) then begin if (Keypressed) then WriteLn('Key waiting at keyboard.'); if (ChWaiting) then WriteLn('Key waiting at modem.'); end; See Also: See Also: See Also: ChWaiting, CRT.Keypressed. BBSkit Manual Page 41 Init CONSTRUCTOR TBBS.Init; CONSTRUCTOR TBBS.Init; CONSTRUCTOR TBBS.Init; Init is the standard means for initializing your program. Even though this method does not contain a virtual virtual virtual keyword, it is still programmer-overridable and should be overridden to initialize your own variables and such. However, you should still call TBBS.Init from within your own Init method to insure that BBSkit can initialize the variables it needs to at runtime. Sample Program Sample Program Sample Program BEGIN TBBS.Init; END. See Also: See Also: See Also: Run, Done. BBSkit Manual Page 42 IntToStr FUNCTION IntToStr(Num : LongInt) : String; FUNCTION IntToStr(Num : LongInt) : String; FUNCTION IntToStr(Num : LongInt) : String; IntToStr converts the long integer (or integer, or word, or byte, etc.) in Num to a string and returns the result as a function. It's basically the way that the Str procedure should have been written from the beginning. ComWrite and ComWriteLn cannot handle non-string types, so IntToStr must be performed on all integer-type value you want to send out the serial port. Sample Program Sample Program Sample Program ComWriteLn('Calls: ' + IntToStr(TotalCalls)); See Also: See Also: See Also: StrToInt. BBSkit Manual Page 43 Left FUNCTION Left(Strn : String; Places : Byte) : String; FUNCTION Left(Strn : String; Places : Byte) : String; FUNCTION Left(Strn : String; Places : Byte) : String; Left left-justifies Strn to Places places. This is for formatting text to a uniform width, and pushes all the text in Strn to left side of the justified string. If needed, spaces are added to the end of the string before it is returned as the function result. If Strn is more than Places characters long, Strn will be truncated to a length of Places, and no left-justifying will be done (it isn't needed in that case). See Also: See Also: See Also: Center, Space, Right. BBSkit Manual Page 44 LoadEmulation FUNCTION TBBS.LoadEmulation(Fname : String) : Boolean; FUNCTION TBBS.LoadEmulation(Fname : String) : Boolean; FUNCTION TBBS.LoadEmulation(Fname : String) : Boolean; LoadEmulation loads a previously defined emulation template into memory from the filename contained in Fname. Fname should not contain an extension, as ".EMU" is automatically added by LoadEmulation. If the template was loaded without error, TRUE is returned. If any errors were detected, FALSE is returned. Once a template is loaded, any calls to the Emu_... procedures will use the new codes loaded from the template. The old template in memory is lost, and must be reloaded to be used again. Additional templates can be created with the EmuMaker program, provided on the BBSkit distribution disk. See Also: See Also: See Also: Emu_.... BBSkit Manual Page 45 Lower FUNCTION Lower(Strn : String) : String; FUNCTION Lower(Strn : String) : String; FUNCTION Lower(Strn : String) : String; Lower returns Strn with all of its uppercase characters converted to lower case. Characters not in the range 'A'..'Z' are unaffected. Sample Program Sample Program Sample Program WriteLn(Lower('BBSkit')); Sample Run Sample Run Sample Run bbskit See Also: See Also: See Also: Upper. BBSkit Manual Page 46 Online FUNCTION TBBS.Online : Boolean; FUNCTION TBBS.Online : Boolean; FUNCTION TBBS.Online : Boolean; Online returns the status of the carrier detect (CD) line of the current COM port. If a carrier is detected, Online returns TRUE. Otherwise, Online returns FALSE. Sample Program Sample Program Sample Program while (Online) do begin WriteLn('Still online!'); end; WriteLn('Carrier lost!'); See Also: See Also: See Also: CarrierLost. BBSkit Manual Page 47 OpenPort PROCEDURE TBBS.OpenPort(Comport : Byte); PROCEDURE TBBS.OpenPort(Comport : Byte); PROCEDURE TBBS.OpenPort(Comport : Byte); OpenPort initializes Comport for use by BBSkit routines. If Comport is equal to 1, then COM1 will be used. If Comport equals 2, then COM2 will be used, up to COM4. Support for serial ports beyond COM4 is not provided. OpenPort must must must be called before any other serial port routines are used, unless the FOSSIL has already been initialized by another program. In general, though, OpenPort is a requirement. Sample Program Sample Program Sample Program OpenPort(1); {use COM1} ComWriteLn('Hello, World.'); ClosePort; See Also: See Also: See Also: ClosePort, SetPort. BBSkit Manual Page 48 PickupPhone PROCEDURE TBBS.PickupPhone; PROCEDURE TBBS.PickupPhone; PROCEDURE TBBS.PickupPhone; PickupPhone will pick up the phone using the currently active answer mode. If the answer mode is set to originate, then PickupPhone will pick up the phone and wait for a carrier from the remote modem. If answer mode is set to answer, then PickupPhone will pick up the phone, send a carrier, and wait for the remote modem to connect to your modem. In either case, PickupPhone does not do the actual waiting. Rather, you must write code to detect whether a connection was established. Sample Program Sample Program Sample Program (see sample program for TBBS.Dial) See Also: See Also: See Also: SetAnswerMode. BBSkit Manual Page 49 PutScreenWord PROCEDURE PutScreenWord(X, Y : Byte; Attr : Byte; Ch : PROCEDURE PutScreenWord(X, Y : Byte; Attr : Byte; Ch : PROCEDURE PutScreenWord(X, Y : Byte; Attr : Byte; Ch : Char); Char); Char); PutScreenWord places the character Ch in video memory at absolute location X,Y with the attribute byte set to Attr. This procedure goes directly to video memory, and may cause snow on some old CGA systems. However, it is also a bit faster, and does not relocate the cursor after placing the character on-screen. See Also: See Also: See Also: GetScreenWord. BBSkit Manual Page 50 PutText PROCEDURE PutText(X, Y : Byte; var Src); PROCEDURE PutText(X, Y : Byte; var Src); PROCEDURE PutText(X, Y : Byte; var Src); PutText places the text in Src at absolute screen coordinates X,Y. PutText goes directly to video memory and may cause snow on old CGA systems. The text placed on-screen must have been previously captured using the GetText call, or else random garbage will result. See Also: See Also: See Also: GetText. BBSkit Manual Page 51 Receive FUNCTION TBBS.ReceiveXmodem(Fname : ComStr) : Boolean; FUNCTION TBBS.ReceiveXmodem(Fname : ComStr) : Boolean; FUNCTION TBBS.ReceiveXmodem(Fname : ComStr) : Boolean; There is currently one transfer protocol available directly to BBSkit programmers: Xmodem. Registered versions of BBSkit will include support for Xmodem/CRC, Xmodem/1K, and Zmodem. ReceiveXmodem is called with a single filename as its argument, such as ReceiveXmodem('TEMP'). Xmodem is probably the most widely used error checking protocol in the BBS community, although it is slow. Error checking is done with a simple checksum. Xmodem uses 128 byte "packets." A packet is all of the information sent to the other end in a transfer at one time. All protocol receive functions return a boolean value depending on whether the file transfer(s) were successful. TRUE is returned if there were no problems, and FALSE otherwise. The programmer is expected to take care of failed transfers. BBSkit does not delete or otherwise change files which are the results of a failed transfer. The protocol is operator-abortable by pressing ESCape on the local keyboard. Sample Program Sample Program Sample Program Success := ReceiveXmodem(Filename); if (not Success) then ComWriteLn('Transfer failed.') else ComWriteLn('Transfer successful.'); See Also: See Also: See Also: SendXmodem. BBSkit Manual Page 52 Replicate FUNCTION Replicate(Ch : String; Num : Byte) : String; FUNCTION Replicate(Ch : String; Num : Byte) : String; FUNCTION Replicate(Ch : String; Num : Byte) : String; Replicate creates a string consisting of Num occurances of Ch, one after the other, in string format. Although Ch can be multiple characters, this function is mainly intended for creating long, non-space areas of text, such as menu headers or dividing lines. Sample Program Sample Program Sample Program WriteLn(Replicate('BBSkit', 3)); Sample Run Sample Run Sample Run BBSkitBBSkitBBSkit See Also: See Also: See Also: Space. BBSkit Manual Page 53 Right FUNCTION Right(Strn : String; Places : Byte) : String; FUNCTION Right(Strn : String; Places : Byte) : String; FUNCTION Right(Strn : String; Places : Byte) : String; Right will right justify Strn to a length of Places. If spaces are needed to make Strn Places long, they will be added to the beginning of the string, pushing the text over and right justifying it. The justified string is returned as the function result. If Strn is more than Places long, the text on the left side of Strn will be truncated to make it Places long. See Also: See Also: See Also: Center, Left, Space. BBSkit Manual Page 54 Ringing FUNCTION TBBS.Ringing : Boolean; FUNCTION TBBS.Ringing : Boolean; FUNCTION TBBS.Ringing : Boolean; Ringing will return the status of the ring indicator (RI) line on the current serial port. If a ring has been detected, Ringing will return TRUE. Otherwise, Ringing will return FALSE. This method is mainly for use in wait for call loops. Sample Program Sample Program Sample Program while (not Ringing) and (not Keypressed) do begin GotoXY(1, 1); Write('Waiting For Call: ', Time); end; BBSkit Manual Page 55 Run PROCEDURE TBBS.Run; VIRTUAL; PROCEDURE TBBS.Run; VIRTUAL; PROCEDURE TBBS.Run; VIRTUAL; Run is a virtual method that does all of the work for your version of TBBS. This routine should contain all of your BBS driving code, and should only exit when the BBS is ready to be shut down. Typically, it is called in the main block of your program, right after Init Init Init and right before Done Done Done. See Also: See Also: See Also: Done, Init. BBSkit Manual Page 56 SendAT FUNCTION TBBS.SendAT(Cmd : String) : Boolean; FUNCTION TBBS.SendAT(Cmd : String) : Boolean; FUNCTION TBBS.SendAT(Cmd : String) : Boolean; SendAT will send Cmd out the current serial port, and wait for an "OK" response from the modem for two seconds. If this response is not detected within two seconds, SendAT returns FALSE. If the response is detected, SendAT returns TRUE. All AT commands must be prefixed with the "AT" command prefix. SendAT does not add this header to commands sent to it to remain compatible with the escape sequence, which does not use an AT prefix. It does, however, append a carriage return to the end of Cmd. Sample Program Sample Program Sample Program while (not SendAT('ATZ')) do WriteLn('Modem not responding. Trying again...'); See Also: See Also: See Also: WaitFor. BBSkit Manual Page 57 Send FUNCTION TBBS.SendXmodem(Fname : ComStr) : Boolean; FUNCTION TBBS.SendXmodem(Fname : ComStr) : Boolean; FUNCTION TBBS.SendXmodem(Fname : ComStr) : Boolean; There is one protocol directly available to BBSkit programmers for sending files to a remote modem: Xmodem. Registered versions include support for sending files with Xmodem/CRC, Xmodem/1K, and Zmodem. SendXmodem is called with a single filename as its argument. Xmodem is an error checking protocol, using checksum error checking and 128 byte packets. It is slow but widely available. All protocols return a boolean value determining whether they were successful. A TRUE value means that all transfers were successful, while a FALSE value means that the file (in the case of the Xmodem protocols) or one of the files (with Zmodem) failed to transfer correctly. The protocol is operator-abortable by pressing ESCape on the local keyboard. Sample Program Sample Program Sample Program Success := SendXmodem(Filename); if (not Success) then ComWriteLn('Transfer failed.') else ComWriteLn('Transfer successful.'); See Also: See Also: See Also: ReceiveXmodem. BBSkit Manual Page 58 SetAnswerMode PROCEDURE TBBS.SetAnswerMode(Status : Byte); PROCEDURE TBBS.SetAnswerMode(Status : Byte); PROCEDURE TBBS.SetAnswerMode(Status : Byte); SetAnswer mode will set the answer mode for the method PickupPhone. To avoid confusion, you should use the constants Originate Originate Originate and Answer Answer Answer which are provided with BBSkit. Although SetAnswerMode will accept other values, the results are unpredictable. Originate Originate Originate mode causes PickupPhone to send ATD out the serial port when it is called. Answer Answer Answer mode causes an ATA to be sent. In both cases, the phone is taken off-hook and a carrier can then be waited for and acted upon. Sample Program Sample Program Sample Program SetAnswerMode(Answer); Repeat Until (Ringing); PickupPhone; WaitFor('C', 30); if (Online) then LogUser else Recycle; See Also: See Also: See Also: GetAnswerMode. BBSkit Manual Page 59 SetBps PROCEDURE TBBS.SetBps(Bps : Word); PROCEDURE TBBS.SetBps(Bps : Word); PROCEDURE TBBS.SetBps(Bps : Word); SetBps sets the baud rate on the current serial port to Bps. Legal values are 300, 600, 1200, 2400, 4800, 9600, 19200, and 38400. Other values will not work because they are not supported by current FOSSIL specifications. This method must be called before any calls to GetBps, or BBSkit will not be able to accurately identify the rate of a serial port. Sample Program Sample Program Sample Program SetBps(2400); if (not SendAT('ATZ')) then begin WriteLn('Modem not responding.'); Halt(1); end else WaitForCall; See Also: See Also: See Also: GetBps. BBSkit Manual Page 60 SetCarrierChk PROCEDURE TBBS.SetCarrierChk(Status : Boolean); PROCEDURE TBBS.SetCarrierChk(Status : Boolean); PROCEDURE TBBS.SetCarrierChk(Status : Boolean); This method sets the mode of carrier checking on the current serial port during any wait-for-key loops (ComReadKey, ComReadKeyE, ComReadLn, ComReadLnWrap). If a carrier is lost while inside one of these loops, it will exit and allow the calling code to check for a lost carrier, and take whatever action is necessary. It is provided to keep users from being able to "crash" your BBS by hanging up on it. See Also: See Also: See Also: SetTime, SetTimeDelay. BBSkit Manual Page 61 SetCaptureFile PROCEDURE TBBS.SetCaptureFile(Path : ComStr); PROCEDURE TBBS.SetCaptureFile(Path : ComStr); PROCEDURE TBBS.SetCaptureFile(Path : ComStr); SetCaptureFile determines where text will be sent when file capturing is turned on. This allows you to create files of entire user sessions, documenting what they did at any point in their session. It can also be used as a capture buffer or "backscroll" feature for a terminal program. The default file is SESSION.TXT, in the current directory. Path can be any legal DOS pathname, up to 127 characters, including drive and subdirectory identifiers. Sample Program Sample Program Sample Program SetCaptureFile('LEECH.TXT'); SetCaptureStatus(True); ComWriteLn('Session recording has been turned on.'); See Also: See Also: See Also: SetCaptureStatus, SetPrinter. BBSkit Manual Page 62 SetCaptureStatus PROCEDURE TBBS.SetCaptureStatus(Status : Boolean); PROCEDURE TBBS.SetCaptureStatus(Status : Boolean); PROCEDURE TBBS.SetCaptureStatus(Status : Boolean); SetCaptureStatus turns on or off session capturing to the file specified by SetCaptureFile, or to SESSION.TXT if no call to SetCaptureFile is made. All text transferred out through either ComWrite or ComWriteLn, as well as all input made through the Comxxx calls, will be copied to this file if Status is TRUE. The file is closed and saved when Status is FALSE. See Also: See Also: See Also: SetCaptureFile, SetPrinter. BBSkit Manual Page 63 SetEcho PROCEDURE TBBS.SetEcho(Ch : Char); PROCEDURE TBBS.SetEcho(Ch : Char); PROCEDURE TBBS.SetEcho(Ch : Char); SetEcho sets the character to be echoed when input from the modem is echoed back to the modem (through ComReadKeyE, ComReadLn, or ComReadLnWrap). It is useful for the input of passwords, but not much else. This echoing can be turned off by passing SetEcho a null value (#0). Sample Program Sample Program Sample Program ComWrite('Enter password, stars echo: '); SetEcho('*'); ComReadLn(Password, 10); SetEcho(#0); { turn echoing off } BBSkit Manual Page 64 SetInput PROCEDURE TBBS.SetInput(Console, Remote : Boolean); PROCEDURE TBBS.SetInput(Console, Remote : Boolean); PROCEDURE TBBS.SetInput(Console, Remote : Boolean); SetInput controls how input is accepted into the input routines (ComReadKey, ComReadKeyE, ComReadLn, and ComReadLnWrap). If Console is TRUE, then input from the local keyboard will be accepted. If FALSE, input will be ignored. If Remote is TRUE, then input from the current serial port will be accepted. If FALSE, it will be ignored. Sample Program Sample Program Sample Program SetInput(True, False); { console only } SetOutput(True, False); ComWrite('New security level: '); ComReadLn(Security, 5); { let sysop input, user } { can't see it } SetInput(True, True); { console and modem } SetOutput(True, True); See Also: See Also: See Also: GetInput, GetOutput, SetOutput. BBSkit Manual Page 65 SetIntChar PROCEDURE TBBS.SetIntChar(Ch : Char); PROCEDURE TBBS.SetIntChar(Ch : Char); PROCEDURE TBBS.SetIntChar(Ch : Char); SetIntChar defines what key will act as the interrupter for files when viewing a file through TypeFile. If the interrupt character is pressed, the file is stopped and TypeFile returns to the calling code. If Ch is null (#0), then the file cannot be interrupted. The default is a space (#32). See Also: See Also: See Also: SetPauseChar, TypeFile. BBSkit Manual Page 66 SetLF PROCEDURE TBBS.SetLF(Status : Boolean); PROCEDURE TBBS.SetLF(Status : Boolean); PROCEDURE TBBS.SetLF(Status : Boolean); SetLF controls the sending of line feeds (#10) after carriage returns (#13). This affects both output to the modem and output to the local console. When set to TRUE, every time a ComWriteLn(...) is executed, a line feed is sent out as well. When set to FALSE, no line feeds are appending to carriage returns. This is mainly used for output to the main console, although some terminal emulations need it as well. BBSkit Manual Page 67 SetNulls PROCEDURE TBBS.SetNulls(Nulls : Byte); PROCEDURE TBBS.SetNulls(Nulls : Byte); PROCEDURE TBBS.SetNulls(Nulls : Byte); SetNulls determines how many nulls to send after each carriage return. Some older terminals require a slight pause between lines, and nulls are the only non-printing, non-command character these terminals can process. Therefore, setting nulls to 4 or 5 can give older terminals the time they need to "catch up" with the transmission. If nulls are needed and not used, the first few characters from each line are usually lost. BBSkit Manual Page 68 SetOutput PROCEDURE TBBS.SetOutput(Console, Remote : Boolean); PROCEDURE TBBS.SetOutput(Console, Remote : Boolean); PROCEDURE TBBS.SetOutput(Console, Remote : Boolean); SetOutput controls output redirection from ComWrite and ComWriteLn. If Console is TRUE, output from these methods is sent out to the screen. If FALSE, no output is seen at the local terminal. If Remote is TRUE, output is sent to the serial port. If FALSE, no output is seen at the remote terminal. See Also: See Also: See Also: GetInput, GetOutput, SetInput. BBSkit Manual Page 69 SetPaging PROCEDURE TBBS.SetPaging(Status : Boolean); PROCEDURE TBBS.SetPaging(Status : Boolean); PROCEDURE TBBS.SetPaging(Status : Boolean); SetPaging controls the pause at the end of each page of text. If Status is set to TRUE, every page of text will end with a (more...) prompt, and a pause for a keypress. If Status is FALSE, text scrolls by without any pauses. The length of a screen can be set by a call to SetPagingLines. The message sent at the end of each page can be set by a call to SetPagingMsg. The internal counter which determines when a page of text has been reached is reset each time the user pressed a key and after the keypress following the (more...) prompt. Sample Program Sample Program Sample Program SetPaging(True); SetPagingLines(24); SetPagingMsg('(more...)'); TypeFile('READ.ME'); See Also: See Also: See Also: SetPagingLines, SetPagingMsg. BBSkit Manual Page 70 SetPagingLines PROCEDURE TBBS.SetPagingLines(Num : Byte); PROCEDURE TBBS.SetPagingLines(Num : Byte); PROCEDURE TBBS.SetPagingLines(Num : Byte); SetPagingLines determines how long the screen is for screen pausing. The default is 24. Pausing is not turned on until a call to SetPaging is made. See Also: See Also: See Also: SetPaging, SetPagingMsg. BBSkit Manual Page 71 SetPagingMsg PROCEDURE TBBS.SetPagingMsg(Msg : String); PROCEDURE TBBS.SetPagingMsg(Msg : String); PROCEDURE TBBS.SetPagingMsg(Msg : String); This method allows the programmer to customize the way a user is told a page of test has been reached. Note that the page pausing routine currently implemented does not allow for "Continue? Yes/No/Continuous" type prompts, because a keypress is not processed at the end of a page of text. Therefore, this prompt should just convey the idea that the user must press a key to continue viewing the text on his screen. See Also: See Also: See Also: SetPaging, SetPagingLines. BBSkit Manual Page 72 SetPauseChar PROCEDURE TBBS.SetPauseChar(Ch : Char); PROCEDURE TBBS.SetPauseChar(Ch : Char); PROCEDURE TBBS.SetPauseChar(Ch : Char); SetPauseChar determines what character will stop output when typing a file using TypeFile. It is an alternative to various types of flow control since FOSSIL based flow control does not allow BBSkit to do any inactivity checking while waiting for a key. SetPauseChar can be of any case. The check for a pause key being pressed is not case sensitive. The default is P. Once the file has been paused, any key will restart it. See Also: See Also: See Also: SetIntChar, TypeFile. BBSkit Manual Page 73 SetPort PROCEDURE TBBS.SetPort(Comport : Byte); PROCEDURE TBBS.SetPort(Comport : Byte); PROCEDURE TBBS.SetPort(Comport : Byte); Sets the current COM port to Comport. This is useful for setting the comport in applications where the FOSSIL driver should already be initialized, such as in doors and other external programs used by a BBS. Comport must be in the range of 1 - 4, inclusive, or the call is ignored. See Also: See Also: See Also: OpenPort. BBSkit Manual Page 74 SetPrinter PROCEDURE TBBS.SetPrinter(Status : Boolean); PROCEDURE TBBS.SetPrinter(Status : Boolean); PROCEDURE TBBS.SetPrinter(Status : Boolean); SetPrinter controls the status of printer dumping of a session in progress. The printer to be used must be accessible through Pascal's Lst pseudo-file, which sends data to the printer. The "Printer" unit need not be included in your program, but it must be available at compile-time. If Status is set to TRUE, all text output through ComWrite and ComWriteLn will be sent to the printer, and all input from the ComReadKey, ComReadKeyE, ComReadLn, and ComReadLnWrap calls will also be sent to the printer. See Also: See Also: See Also: SetCaptureFile, SetCaptureStatus. BBSkit Manual Page 75 SetTimer PROCEDURE TBBS.SetTimer(Status : Boolean); PROCEDURE TBBS.SetTimer(Status : Boolean); PROCEDURE TBBS.SetTimer(Status : Boolean); This method controls monitoring of user inactivity. When Status is TRUE, and the user has been idle for the amount of time specified by SetTimerDelay, BBSkit will send a short message to the user, telling him of the impending logoff. If 30 additional seconds pass, and the user has not pressed a key, the input routine will be cancelled and the CarrierLost function will act as if carrier had been lost. Your code should check CarrierLost and act as if the user had hung up on instead of trying to determine whether or not carrier was actually lost. See Also: See Also: See Also: CarrierLost, SetTimerDelay. BBSkit Manual Page 76 SetTimerDelay PROCEDURE TBBS.SetTimerDelay(Dly : Word); PROCEDURE TBBS.SetTimerDelay(Dly : Word); PROCEDURE TBBS.SetTimerDelay(Dly : Word); This method specifies the time interval, in seconds, before BBSkit should treat the situation as a carrier loss. Inactivity checking is turned on and off through the SetTimer method. See Also: See Also: See Also: SetTimer. BBSkit Manual Page 77 ShowCursor PROCEDURE ShowCursor; PROCEDURE ShowCursor; PROCEDURE ShowCursor; ShowCursor turns the local screen text cursor on after it was previously turned off with the HideCursor procedure. See Also: See Also: See Also: HideCursor. BBSkit Manual Page 78 Space FUNCTION Space(Num : Byte) : String; FUNCTION Space(Num : Byte) : String; FUNCTION Space(Num : Byte) : String; Space returns a string consisting of Num spaces. It is mainly used for aligning text out from the left side of the screen, without having to insert literal spaces into your code. See Also: See Also: See Also: Center, Left, Replicate, Right. BBSkit Manual Page 79 StrToInt FUNCTION StrToInt(Strn : String) : LongInt; FUNCTION StrToInt(Strn : String) : LongInt; FUNCTION StrToInt(Strn : String) : LongInt; StrToInt converts the string Strn into the equivalent long integer and returns it as a function. It is the procedure Val in function form, like it should have been from the beginning. ComReadLn and ComReadLnWrap cannot handle input of non- string types, so any numbers entered from these procedures must first be converted into an integer-type to be used by the programmer. Sample Program Sample Program Sample Program ComWrite('Lines per page: '); ComReadLn(Inp, 3); Lines := StrToInt(Inp); See Also: See Also: See Also: IntToStr. BBSkit Manual Page 80 SwapB PROCEDURE SwapB(var A : Byte); PROCEDURE SwapB(var A : Byte); PROCEDURE SwapB(var A : Byte); SwapB will swap the high and low order hex digits of a byte. It is useful for reversing the text attributes and swapping the foreground and background colors. It isn't useful for much else, however. (At least, nothing the author can think of right now.) Sample Program Sample Program Sample Program Temp := $12; SwapB(Temp); Sample Watch Sample Watch Sample Watch Temp,h : $21 If you want to send hex numbers to the screen, you will have to write your own function or procedure to do so. Turbo Pascal doesn't include one. However, using a watch is sufficient for this sample. See Also: See Also: See Also: SYSTEM.Swap. BBSkit Manual Page 81 TerminalMode FUNCTION TBBS.TerminalMode(Duplex : Byte) : Char; FUNCTION TBBS.TerminalMode(Duplex : Byte) : Char; FUNCTION TBBS.TerminalMode(Duplex : Byte) : Char; TerminalMode provides the closest contact with the modem that BBSkit provides a user. Duplex contains one of two values, which are represented by constants. If Duplex is Full Full Full, then no character typed at the local console is sent to the screen. If Duplex is Half Half Half, every character typed at the keyboard will also appear at the screen. All characters typed are sent out the serial port, and any characters coming through the serial port will appear on the local screen. TerminalMode exits when one of the extended keycodes is detected by Pascal. These include the Alt- keys, some Control- keys, function keys, and others. For a complete list, and the codes that go with each key, check your Pascal manuals under "Extended Key Codes." BBSkit Manual Page 82 TextMemSize FUNCTION TextMemSize(X1, Y1, X2, Y2 : Byte) : Word; FUNCTION TextMemSize(X1, Y1, X2, Y2 : Byte) : Word; FUNCTION TextMemSize(X1, Y1, X2, Y2 : Byte) : Word; TextMemSize returns the amount of memory required for a GetText call using the coordinates X1,Y1 to X2,Y2. All coordinates are absolute screen coordinates, not relative to the current window. The memory required for a GetText call is equal to the width of the box * 2, multiplied by the height of the box, plus 2. Each character on-screen requires two bytes. The first is the actual character, and the second is the attribute byte. The attribute byte determines what color the character is, its background, and if the character blinks. Two more bytes are required for PutText to know how large the text is that it is placing on-screen. See Also: See Also: See Also: GetText, PutText. BBSkit Manual Page 83 Time FUNCTION Time : String; FUNCTION Time : String; FUNCTION Time : String; Time returns the current time from the internal clock (if any) or from DOS (if there is no clock) and formats into the form HH:MM[a/p]. Therefore, 12:00 noon would be returned as 12:00p, and 8 in the morning would be returned as 8:00a. (There is a leading space for times when the hour only takes up one digit.) The length of the string returned by Time is always always always 6 characters. See Also: See Also: See Also: Date. BBSkit Manual Page 84 TypeFile PROCEDURE TBBS.TypeFile(Fname : String); PROCEDURE TBBS.TypeFile(Fname : String); PROCEDURE TBBS.TypeFile(Fname : String); TypeFile acts exactly like the DOS equivalent, but also sends text to the serial port and/or screen depending on SetOutput. The file can be paused if the key defined by SetPauseChar is pressed, and stopped if the key defined by SetIntChar is pressed. See Also: See Also: See Also: SetIntChar, SetPauseChar. BBSkit Manual Page 85 Upper FUNCTION Upper(Strn : String) : String; FUNCTION Upper(Strn : String) : String; FUNCTION Upper(Strn : String) : String; Upper will make Strn consist completely of uppercase characters. Characters not in the range of 'a'..'z' are unaffected. Sample Program Sample Program Sample Program WriteLn(Upper('BBSkit')); Sample Run Sample Run Sample Run BBSKIT See Also: See Also: See Also: Lower. BBSkit Manual Page 86 VersionID FUNCTION VersionID : String; FUNCTION VersionID : String; FUNCTION VersionID : String; Returns a string reporting the version of BBSkit, who wrote it, the release date, and whether it is registered or unregistered. This function was added instead of using a title line at the beginning of each program that used BBSkit. Your programs can now also report the version of BBSkit used without anything more complex than a recompile for a newer version. BBSkit Manual Page 87 WaitFor FUNCTION TBBS.WaitFor(Strn : String; Timeout FUNCTION TBBS.WaitFor(Strn : String; Timeout FUNCTION TBBS.WaitFor(Strn : String; Timeout : Word) : : Word) : : Word) : Boolean; Boolean; Boolean; WaitFor will wait for Strn to come through the serial port in Timeout seconds or less. If the string is seen, WaitFor returns a TRUE value. Otherwise, it returns FALSE. WaitFor is not case sensitive, and does no differentiate between whole words and partial words. Therefore, WaitFor would return TRUE while waiting for an "e" if the following string came through the serial port: BBSkit is neat! This method does make use of the serial port's input buffer, though, so all characters up to the "a" in "neat" would be lost. The only characters remaining in the buffer after that call would be "at!". WaitFor is primarily used for checking to see if the modem received a sent command. The method SendAT SendAT SendAT calls WaitFor after sending a command out the serial port, and has it wait two seconds for an "OK" string to be sent back. WaitFor can also be used to find out what baud a caller has connected at: Sample Program Sample Program Sample Program if (WaitFor('CONNECT', 30)) then begin ComReadLn(Result, 40); { read in result code } Bps := IntToStr(Copy(Result, 2, 5)); if (Bps = 0) then Bps := 300; SetBps(Bps); end; This code works because a common connect string, such as CONNECT 1200, would be seen. " 1200" would remain in the input buffer, so the programmer would turn all character past the leading space into a number, and use that number to set the bit rate. If that number were 0, it would mean that there was no text following the CONNECT, so you must be running at 300 baud. Note that some modems must be told specifically to send the extended CONNECT codes if they do not do so as default. See Also: See Also: See Also: SendAT. BBSkit Manual Page 88 XPos FUNCTION XPos(Strn, SubStrn : String; Offset : Byte) : Byte; FUNCTION XPos(Strn, SubStrn : String; Offset : Byte) : Byte; FUNCTION XPos(Strn, SubStrn : String; Offset : Byte) : Byte; XPos returns the first occurance of SubStrn within Strn starting at Offset into Strn. This function is an extension of the standard function Pos, which does not allow for finding multiple occurances of the sub-string. Please note that XPos makes a more logical approach to searching a string for a sub-string, and the string to search in comes first, while the string to locate in that string comes second. (Pos reverses it. The sub-string comes before the string.) The result of this function is the absolute offset at which the sub-string starts within the string, or zero if no occurance was found. Sample Program Sample Program Sample Program WriteLn(XPos('Hi! Hi!', 'Hi', 3)); Sample Run Sample Run Sample Run 5 BBSkit Manual Page 89